
SnipeHud v1.21

Written by Tim "Zear" Hammock (zear@planetstarsiege.com)
April 6 - 28, 1999

    Thanks to Cowboy for the crosshair code snippet - genius
    Thanks to DS.Poker for the basis for my zoom-setting-chain-thingy
    Thanks to Presto for most of the 1.01 changes
    Thanks to the 1.1 beta testers for the many corrections and suggestions

==============================================================================

Contents:

I.   Installation
II.  Settings
III. Version history

==============================================================================

I. Installation:
----------------
    
 ****************************************************************************
 *                                                                          *
 *   Note: This script _requires_ the Presto Pack version 0.93 or better.   *
 *                                                                          *
 ****************************************************************************

1. If you don't already have one, create a '<tribes>\config\zear' folder.

2. Unzip SnipeHud.cs into the 'zear' folder.

3. In your <tribes>\config\autoexec.cs file, anywhere after the line

        exec("presto\\autoexec.cs");
        
   add the line
   
        Include("zear\\SnipeHud.cs");

4. Customize the settings as explained in section II, Settings, below.

5. (Re)start Tribes.

==============================================================================

II.  Settings:
--------------


-> Position and size:

These are set via the variable $SnipeHud::position on line 52. The string
assigned to $SnipeHud::position follows the format

    "x y width height"

with x indicating the distance from the left edge of the screen, and y
indicating the distance from the top edge of the screen. If you play Tribes in
a window, these measurements will of course be from the appropriate edge of
the Tribes window.

The position and size can be set either relative to the size of the screen, or
by exact pixel measurement. For instance, the default setting is

    $SnipeHud::position = "100% 100% 30% 30%";
    
This default setting uses relative measurement. The x value of 100% indicates
that the SnipeHud should be placed all the way to the right edge of the
screen. The y value of 100% indicates that the SnipeHud should be placed all
the way to the bottom edge of the screen. The width and height values indicate
that the hud should be 30% as wide as the screen and 30% as high as the screen
as well.

Using relative placement, the SnipeHud could be placed in the middle of the
screen using

    $SnipeHud::position = "50% 50% 30% 30%";
    
To use exact pixel measurements, simply omit the '%' symbols. For instance

    $SnipeHud::position = "400 240 240 240";
    
would place the SnipeHud's upper left corner 400 pixels across and 240 pixels
down from the screen's upper left corner, and will give the SnipeHud a size of
240x240. This would place a rather large view in the bottom-right corner of a
640x480 screen.

Keep in mind that relative placement will adjust for screen size automatically,
whereas exact pixel placement will not.

                                 ------------
                                 

-> Zoom on/off toggle:

To set the key that will toggle the SnipeHud on and off, set
$SnipeHud::zoomToggle on line 55 equal to the desired key. The default key is
the semicolon (';').

When you turn on the SnipeHud, the zoom level should be where you left it at
last use (unless you have not used it before, in which case it will default to
the lowest available zoom setting - see 'Zoom step settings').

See the sections on 'Initial-on', and 'Momentary Zoom' below for more
information.

                                 ------------
                                 

-> Sensitivity on/off toggle:

To set the key that will toggle custom mouse sensitivity on and off, set
$SnipeHud::sensitivity on line 58 equal to the desired key. The default key is
the 'l' (lowercase 'L').

The text of the magnification indicator will be white when custom mouse
sensitivity is activated, and brown when it is inactive.

You cannot toggle the custom mouse sensitivity on when the SnipeHud is not
visible.

See the sections on 'Active/Passive sensitivity' and 'Zoom step settings'
below for more information.

                                 ------------
                                 

-> Zoom-in and zoom out keys:

To set the keys that will zoom in or out one step, set $SnipeHud::zoomInKey
and $SnipeHud::zoomOutKey (on lines 61 and 63 respectively) equal to the
desired keys. The default key for zoom-in is the period ('.'), and the default
for zoom-out is the comma (',').

You can increase or decrease the zoom while the SnipeHud is not visible, but
doing so will no longer automatically activate the SnipeHud as in previous
versions.

See the sections on 'Active/Passive sensitivity' and 'Zoom step settings'
below for more information.
	
                                 ------------
                                 

-> Sniper-style crosshair:

SnipeHud supports two crosshair types: a small + shaped crosshair, or the
sniper-style crosshair, which extends to the edges of the hud. The default
is false (use small crosshair).

To set SnipeHud to use the sniper-style crosshair, set line 65 to

    $SnipeHud::sniperCrosshair = true;

To use the small crosshair, set line 65 to

    $SnipeHud::sniperCrosshair = false;
	
                                 ------------
                                 

-> Hud frame:

SnipeHud can show a frame around the hud, or not. The default is true (show
the frame).

To set SnipeHud to show the frame, set line 68 to

    $SnipeHud::showFrame = true;

To disable the frame, set line 68 to

    $SnipeHud::showFrame = false;
	
                                 ------------
                                 

-> Magnification indicator:

SnipeHud can display a magnification level indicator in the corner of the hud
window. The default is true (show the indicator).

In addition, the text of the magnification indicator will be white when
custom mouse sensitivity is activated, and brown when it is inactive.

To set SnipeHud to show the indicator, set line 71 to

    $SnipeHud::showMag = true;

To hide the indicator, set line 71 to

    $SnipeHud::showMag = false;
	
                                 ------------
                                 

-> Initial-on:

SnipeHud can be set up to automatically activate when you start Tribes. The
default is false (do not show SnipeHud automatically).

To set SnipeHud to automatically activate, set line 74 to

    $SnipeHud::initialOn = true;

To disable this feature, set line 74 to

    $SnipeHud::initialOn = false;

                                 ------------
                                 

-> Active/Passive sensitivity:

SnipeHud alters your mouse sensitivity based on the current zoom level. The
sensitivity is limited to Tribes' sensitivity range, which defaults to values
between 0.0002 (most sensitive) and 0.004. If you flip your mouse's X or Y
axis, SnipeHud will take that into account automatically.

There are two modes of sensitivity: active and passive.

Active sensitivity means that the mouse sensitivity is adjusted automatically
when the SnipeHud is active, and can be changed to the default sensitivity by
pressing and holding the sensitivity on/off toggle key.

Passive sensitivity means that the mouse sensitivity is adjusted only
when the sensitivity on/off toggle key is pressed and held.

The default is passive sensitivity.

To set SnipeHud to active sensitivity, set line 77 to

    $SnipeHud::passiveSense = false;

To set SnipeHud to passive sensitivity, set line 77 to

    $SnipeHud::passiveSense = true;

See the section on 'Zoom step settings' below for more information.

                                 ------------
                                 

-> Momentary Zoom:

SnipeHud's Zoom on/off can be activated one of two ways: toggle or momentary.

In toggle mode, pressing the zoom on/off button will activate SnipeHud and
pressing it again will deactivate SnipeHud.

In momentary mode, pressing the zoom on/off button will activate SnipeHud and
releasing it will deactivate SnipeHud.

The default is toggle mode.

To set SnipeHud to toggle mode, set line 80 to

    $SnipeHud::momentary = false;

To set SnipeHud to momentary mode, set line 80 to

    $SnipeHud::momentary = true;

                                 ------------
                                 

-> Zoom step settings:

For each zoom setting beginning with line 83) there is a line:

    $SnipeHud::set[<zoom>] = "<out> <in> <sens>";

where:

    <zoom> is the zoom factor
    <out> is the next less powerful zoom factor
    <in> is the next more powerful zoom factor
    <sens> is the mouse sensitivity for this zoom factor

An 'x' in the place of <out> or <in> indicates the end of the chain (can't
zoom in/out any farther). You may set as many zoon steps as you like. The
default settings are

    $SnipeHud::set[2] = "x 5 0.003";
    $SnipeHud::set[5] = "2 10 0.002";
    $SnipeHud::set[10] = "5 20 0.001";
    $SnipeHud::set[20] = "10 250 0.0005";
    $SnipeHud::set[250] = "20 x 0.0002";
    
If you wish the zoom to automatically wrap through the zoom list, you could
change this to

    $SnipeHud::set[2] = "250 5 0.003";
    $SnipeHud::set[5] = "2 10 0.002";
    $SnipeHud::set[10] = "5 20 0.001";
    $SnipeHud::set[20] = "10 250 0.0005";
    $SnipeHud::set[250] = "20 2 0.0002";
    
and then zooming in farther than 100x will set the zoom to 2x and vice-versa.

The minimum zoom setting is 1x and the maximim zoom setting is 250x (although
at 250x, details start to fuzz out pretty bad). I cannot guarantee that high
zoom levels will not slow down your display; after all, if you are at a zoom
level of 250x and a resolution of 800x600, Tribes is stretching your regular
view to 200,000 x 150,000 pixels and then cropping it to the size of the hud.
That's bound to be a performance drain!

Keep in mind also that the sensitivity range allowed by Tribes is from 0.0002
to 0.004, and that using values outside that range will have no effect.

    
==============================================================================

III. Version History:
---------------------

New in version 1.21 (4/28/99):
    Added sniper-style crosshair option (more or less)
    Added frameless hud option
    Added 'hide magnification indicator' option
    Magnification indicator changes color to indicate whether or not
        custom mouse sensitivity is active
    Raised max zoom from 20 to 250 (by popular demand). This brings the max
        zoom possible (standard zoom + SnipeHud zoom) to 5000x. I belive you
        will find that this is more magnification than you will ever need.

New in version 1.2 (4/9/99):
    $SnipeHud::position (hud placement) uses newest Presto style
    Zoom level indicator
    Added banner for main menu screen
    Added passive/active toggle for sensitivity
    Added momentary/static toggle
    Mouse x-axis flipping also handled automatically

New in version 1.1 (4/9/99 - No public release):
    Now REQUIRES Presto Pack v0.93 or better
    Crosshair location calculation now works always (thanks Cowboy)
    Mouse y-axis flipping handled automatically (thanks Presto)
    Default mouse sensitivity handled automatically (thanks Presto)

New in version 1.01 (4/8/99):
    Mouse y-axis flipped playstyle supported
    Presto cleaned it up and added relative placement
    Presto also found and fixed a bug in my Presto-ization
        that resulted in multiple view objects being created

New in version 1.0 (4/7/99):
    Mouse sensitivity implemented
    Crosshair
    Window border
    Fixed a 'Doh!' style bug in keybinding
